home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / Implementation / Storage / Bento / CM / Session.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-02-13  |  10.1 KB  |  230 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:             Session.h     
  3.  
  4.     Contains:    Container Manager Session (task) Global Data Definitions
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1992 - 1996 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     1/15/96    TJ        Cleaned Up
  15.          <2>     8/26/94    EL        #1181622 Ownership update.
  16.          <1>      2/3/94    EL        first checked in
  17.          <2>    11/22/93    EL        Add refcon for alloc and free handers.
  18.  
  19.     To Do:
  20. */
  21.  
  22. /*---------------------------------------------------------------------------*
  23.  |                                                                           |
  24.  |                        <<<      Session.h      >>>                        |
  25.  |                                                                           |
  26.  |         Container Manager Session (task) Global Data Definitions          |
  27.  |                                                                           |
  28.  |                               Ira L. Ruben                                |
  29.  |                                  4/9/92                                   |
  30.  |                                                                           |
  31.  |                    Copyright Apple Computer, Inc. 1992-1994               |
  32.  |                           All rights reserved.                            |
  33.  |                                                                           |
  34.  *---------------------------------------------------------------------------*
  35.  
  36.  Although it is kept to a minimum, the Container Manager needs some global data!  This
  37.  header defines that data.  It is defined in terms of a struct to group all the globals
  38.  in one place.  The space for the struct is dynamically allocated by CMStartSession(). This
  39.  allows the global data to be associated with a particular running session or task.  Using
  40.  static global data is not necessary supported in some configurations of the Container
  41.  Manager.  For example, in some DLL environments, static global data is not supported.
  42.  
  43.  The scheme chosen here is the most painless (unless you're me who had to change all the
  44.  code to use this thing). The SessionGlobalData struct is known only to the Container
  45.  Manager.  It is allocated by CMStartSession() and returned as an anonomous pointer to be
  46.  passed to the container open routines, CMOpen[New]Container().  All routines, except 
  47.  ones global to all containers, access the session data through a container refNum.
  48.  
  49.  There are some routines that are global to all containers.  Specifically, they are the
  50.  handler operations (e.g, CMSetMetaHandler(), CMGetMetaHandler(), etc.).  All of these
  51.  take the session data pointer explicitly as one of their parameters.
  52. */
  53.  
  54. #ifndef __SESSIONDATA__
  55. #define __SESSIONDATA__
  56.  
  57. #include <stdio.h>
  58. #include <setjmp.h>
  59.  
  60. #ifndef __CMTYPES__
  61. #include "CMTypes.h"
  62. #endif
  63. #ifndef __CM_API_TYPES__
  64. #include "CMAPITyp.h"
  65. #endif
  66. #ifndef __LISTMGR__
  67. #include "ListMgr.h"
  68. #endif
  69. #ifndef __TOCENTRIES__
  70. #include "TOCEnts.h"   
  71. #endif
  72. #ifndef __TOCOBJECTS__
  73. #include "TOCObjs.h"   
  74. #endif
  75. #ifndef __HANDLERS__
  76. #include "Handlers.h"
  77. #endif
  78. #ifndef __CONTAINEROPS__
  79. #include "Containr.h"  
  80. #endif
  81.  
  82. struct MetaHandler;
  83.                                                                     CM_CFUNCTIONS
  84.  
  85.  
  86. /*----------------------------*
  87.  | Session Handler Prototypes |
  88.  *----------------------------*
  89.  
  90.  There are curently three session handlers whose addresses are returned through the session
  91.  metahandler passed to CMStartSession().  These handlers have the following prototypes:
  92. */
  93.  
  94. typedef void CM_PTR *(CM_FIXEDARGS *MallocProto)(CMSize size, CMRefCon sessionRefCon);
  95. typedef void (CM_FIXEDARGS *FreeProto)(CMPtr ptr, CMRefCon sessionRefCon);
  96. typedef void (CM_VARARGS *ErrorProto)(CMErrorNbr errorNumber, ...);
  97.  
  98.  
  99. /*-----------------------------------------------------*
  100.  | SessionGlobalData - all global data is defined here |
  101.  *-----------------------------------------------------*
  102.  
  103.  Note that the Container Manager version number is placed in the session global data as 
  104.  the last item.  It is variable length so it must come at the end to allow for the     
  105.  proper dynamic allocation. This makes it harder to find, but it sould not be a problem.
  106. */
  107.  
  108. struct SessionGlobalData {                            /* Session global data layout:                                    */
  109.     MallocProto cmMalloc;                                    /*         handler's version of malloc()                            */
  110.     FreeProto     cmFree;                                        /*         handler's version of free()                                */
  111.     ErrorProto     cmReportError;                         /*         error reporter                                                        */
  112.     
  113.     jmp_buf cmForEachGlobalNameEnv;                /*         AbortForEachGlobalName() setjmp env.            */
  114.     jmp_buf cmForEachObjectEnv;                        /*         AbortForEachObject() setjmp env.                    */
  115.     
  116.     CM_ULONG cmTocTblSize;                        /*         size of TOC index tables                                    */
  117.     
  118.     FILE *cmDbgFile;                                            /*         debugging trace file                                            */
  119.     
  120.     #if CMDUMPTOC
  121.     CM_ULONG currTOCoffset;                    /*         current input TOC offset for debugging        */
  122.     CMBoolean gotExplicitGen;                                /*        true ==> explicit generation nbr read            */
  123.     #endif
  124.     
  125.     ListHdr openContainers;                                /*         list of open containers                                        */
  126.     struct MetaHandler *metaHandlerTable;    /*         the root of the handler tree                            */
  127.     
  128.     CMRefCon refCon;                                            /*         pointer to additional user supplied data    */
  129.     
  130.     #if CMVALIDATE
  131.     CMBoolean validate;                                            /*         true ==> do refNum validations                         */
  132.     #endif
  133.     
  134.     unsigned char scratchBuffer[256];            /*         ptr to a general short-term scratch buffer*/
  135.     CMBoolean success;                                            /*        special function result status                        */
  136.     CMBoolean    aborting;                                            /*        in "abort" state (abnormal termination)        */
  137.     
  138.     CM_CHAR cmVersion[1];                                        /*         start of CM version nbr (MUST be last)         */
  139. };
  140. typedef struct SessionGlobalData SessionGlobalData, *SessionGlobalDataPtr;
  141.  
  142.  
  143. /* By convention, the variable "container" will always be used to point to the current    */
  144. /* container.  The following macro is used to access the session global data through         */
  145. /* container:                                                                                                                                                        */
  146.  
  147. #define SESSION (((ContainerPtr)container)->sessionData)
  148.  
  149.  
  150. /* Note, some routines must deal directly with the session data instead of accessing it */
  151. /* through the container. By convention, the variable "sessionData" will always be used */
  152. /* as the session pointer.  To make life a little simpler, the following macros are         */
  153. /* defined to access some of the fields in the session data:                                                        */
  154.  
  155. #define SessionRefCon                        (((SessionGlobalDataPtr)sessionData)->refCon)
  156. #define SessionError                         (*(((SessionGlobalDataPtr)sessionData)->cmReportError))
  157. #define SessionMalloc(size)          (*(((SessionGlobalDataPtr)sessionData)->cmMalloc))((CMSize)(size),SessionRefCon)
  158. #define SessionFree(ptr)              (*(((SessionGlobalDataPtr)sessionData)->cmFree))((CMPtr)(ptr),SessionRefCon)
  159.  
  160. #define SessionMetaHandlerTable    (((SessionGlobalDataPtr)sessionData)->metaHandlerTable)
  161.  
  162.  
  163. /* The validate switch in the session data is controlled by CMDebugging() if                         */
  164. /* CMDebugging() itself is allowed to be generated (under its CMDEBUGGING switch macro     */
  165. /* controlled by the header CMTypes.h). It is preset to CMDEFAULT_VALIDATE (also defined*/
  166. /* in CMTypes.h to keep if hidden from the user).                                                                                */
  167.  
  168. /* The validate switch allows for dynamic controlling of the refNum validations and also*/
  169. /* checking for CMStartSession() being called. Thus the code checks can be toggled on or*/
  170. /* off through CMDebugging().                                                                                                                        */
  171.  
  172. /* There is also a static switch to suppress the validation code entirely. It is called */
  173. /* CMVALIDATE, also defined in CMTypes.h.  Of course, if CMVALIDATE is 0, ALL the                */
  174. /* validations are suppressed and the dynamic switch has no effect.                                            */
  175.  
  176. /* Remember, suppressing the validation checks removes what little protection the                */
  177. /* Container Manager has against sadistic (or just plain stupid or careless) users.  If    */
  178. /* this stuff blows, don't bug me!                                                                                                            */
  179.  
  180. /* I am getting off the track.  The whole point here is to define a macro to make it        */
  181. /* easier to access the validate switch...                                                                                            */
  182.  
  183. #if CMVALIDATE
  184. #define VALIDATE (SESSION->validate)
  185. #else
  186. #define VALIDATE 0
  187. #endif
  188.  
  189. /* Since this uses the SESSION macro, container is assumed to be the container pointer.    */
  190.  
  191. /* Also, since we usually get at the container via a refNum, and assuming the validation*/
  192. /* code is not suppressed (CMVALIDATE was 1), we must at least always validate that a        */
  193. /* refNum is not NULL before we use it to go after the session data pointer to see if        */
  194. /* all further validation checking is being dynamically suppressed.                                            */
  195.  
  196.  
  197. /* The following allows access to scratchBuffer as a function of the current container     */
  198. /* pointer via the SESSION macro defined above.                                                                                    */
  199.  
  200. #define ScratchBufr (SESSION->scratchBuffer)
  201.  
  202. /* The following serves the same purpose but uses the session data pointer directly. As    */
  203. /* above, it is assued this pointer is in the variable "sessionData".                                        */
  204.  
  205. #define SessionScratchBufr    (((SessionGlobalDataPtr)sessionData)->scratchBuffer)
  206.  
  207.  
  208. /* Some routines, for example, some of the lookup routines like the metahandler lookup,    */
  209. /* need to do "malloc"s to allocate special temporaries to do their work.     There are         */
  210. /* vary few routines like this.  "Malloc"s, of course, are subject to failure.  So we     */
  211. /* need a way for these routines to report such an error status.  It is confusing and     */
  212. /* inconvenient to have an extra explicit parameter for these routines since the return    */
  213. /* value is always used to indicate a found/not found status.  So the session global,        */
  214. /* "success", is provided for this purpose.                                                                                          */
  215.  
  216. /* The preceding is one use for the switch. It can also be used as an "separate channel"*/
  217. /* to report other status as well.  Fo example, indicating success or failure for             */
  218. /* setjmp/longjmp's, since you cannot use the returned int from a setjmp in a pure ANSI */
  219. /* envoironment!                                                                                                                                                */
  220.  
  221. /* The following macro is provided to interrogate the success/failure status.  This         */
  222. /* assumes "container" is the current container pointer.    Note, routines that use this    */
  223. /* switch must always set it both ways as appropriate. Never assume the previous setting*/
  224. /* of this switch.                                                                                                                                            */
  225.  
  226. #define SessionSuccess (SESSION->success)
  227.  
  228.                                                           CM_END_CFUNCTIONS
  229. #endif
  230.